home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / Tools / D_UHR11E / D_UHR11E.TXT next >
Encoding:
Text File  |  1997-06-16  |  11.0 KB  |  337 lines
  1.  
  2.  
  3.  
  4.                                 'Die Uhr'
  5.  
  6.  
  7.  
  8.                        a digital-clock accessory
  9.  
  10.  
  11.  
  12.                       dokumentation Dec 24, 1992
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  Program by Thomas Birke & Hinnerk Rümenapf
  19.  (C) 1987 - 1992 T.B. & HWR
  20.  
  21.  *Pentagramm Software Braunschweig
  22.  Thomas Birke                                           Hinnerk Rümenapf
  23.  Billrothstr. 31                                        Ottweilerstr. 18
  24.  W-3300 Braunschweig                                    W-3300 Braunschweig
  25.  -------------------
  26.  
  27.  GERMANY
  28.  
  29.  
  30.  'Die Uhr' may be used by everyone who gives a (FREE) copy to anyone
  31.  who might want to use it.
  32.  
  33.  'Die Uhr' may be copied ONLY if ALL the following files are included
  34.  and unchanged:
  35.  
  36.         - DIE_UHR.ACC           the accessory
  37.         - D_UHR11E.TXT          this file
  38.  
  39.         - UHRCONF.PRG           configuration-program for 'Die Uhr'
  40.         - UHRCONF.RSC           resource-file needed by UHRCONF.PRG
  41.  
  42.  
  43.  
  44.  ALL RIGHTS belong to the authors, we're only letting you use it.
  45.  
  46.  There is NO WARRANTY whatsoever. (What do you expect for free ?)
  47.  
  48.  
  49.  History
  50.  
  51.  'Die Uhr' startet off as a test 'how to write an Accessory'. Over the years
  52.  it has seen many changes and new features. The first Version put on an FTP-
  53.  server was labeled 1.0.
  54.  
  55.  
  56.  'Die Uhr' is another clock-accessory, with the following features:
  57.  
  58. Version 1.0  june/july 1992
  59.  
  60.         - pure GEM-program, no vektors changed, no interrupt-routines
  61.  
  62.         - a short but well-known melody on the hour (can be switched off).
  63.  
  64.         - should work with any screen-resolution (we hope - we couldn't try
  65.           them all).
  66.  
  67.         - a change of the screen-resolution without reset ( AS-Overscan,
  68.           PixelWonder, ...) should cause no problems.
  69.  
  70.         - an alarm with a 'time-window'.
  71.           If 'Die Uhr' is blocked at alarm-time (e.g. by TOS-programs)
  72.           it will sound the alarm up to half an hour after the alarm-time
  73.           (if it gets a chance).
  74.  
  75.         - 'Die Uhr' is configurable. the default settings can be changed with
  76.           UHRCONF.PRG.
  77.  
  78.         - we recommend to  "Let 'em fly"  with software by Oliver Scheel.
  79.  
  80.  
  81. version 1.1 Nov/Dez 1992    major changes :
  82.  
  83.         - first version with english documentation: 1.1E
  84.           (german version: 1.1)
  85.  
  86.         - display can be configured (X-position, ... )
  87.  
  88.         - a 12-hour (AM/PM) mode
  89.  
  90.         - the running accessory can be reconfigured without reset
  91.  
  92.         - (a few little bug fixes)
  93.  
  94.  
  95.  And now for the documentation :
  96.  
  97.  
  98.  0. GEM-accessories
  99.  ------------------
  100.  
  101. Accessories are utilitiy-programs which are loaded at system-start and
  102. remain in memory until a restart. Accessories are running 'almost' parallel to
  103. GEM-programs (if those are written correctly).
  104.  
  105. If 'Die Uhr' should stop it could have different reasons :
  106.  
  107.   a GEM - program is running (ending .PRG or .APP)
  108.         Whoever wrote that programm didn't do his job properly.
  109.  
  110.   a TOS - program is running (ending .TOS or .TTP)
  111.         These porgrams usually block ALL accessories.
  112.         If you leave the programm 'Die Uhr' should work again
  113.           - if it doesn't, its either a TOS-fault, or ours.
  114.  
  115.  
  116. If you click the menu entry 'Die Uhr' in the leftmost menu (e.g. title 'DESK')
  117. the accessory will display a dialog (explained below).
  118.  
  119. If your computer does not have a hardware-clock you'll have to set the time
  120. yourself ussing the control-acc., our D_T_E.PRG (D_T.PRG) or any similar
  121. utility.
  122.  
  123.  
  124.  1. Display
  125.  ----------
  126.  
  127. The time is displayed in the top right corner. If the screen resolution
  128. changes (e.g. AS-Overscan) the distance  time-display / right edge  is kept
  129. constant. This distance can be configured.
  130.  
  131. You can select (configure) either a 24- or a 12-hour (AM/PM) display .
  132.  
  133. If time-display AND alarm are switched on, a bell symbol is displayed as well.
  134.  
  135. Some GEM-programs use the whole screen width for their menu. In this case
  136. the time-display may replace some of the last menu title. It doesn't look too
  137. good, but the menu will work.
  138.  
  139. You can switch the time-display on or off in the accessory-dialog.
  140. Use the two buttons right of the clock-symbol (AN = ON, AUS = OFF).
  141. The default-setting is configurable.
  142.  
  143.  
  144.  2. melody on the hour
  145.  ---------------------
  146.  
  147. Listen and enjoy, or turn if off.
  148.  
  149. Every time the hour changes 'Die Uhr' can play a (very) short melody.
  150.  
  151. You can switch the 'melody on the hour' on or off in the accessory-dialog.
  152. Use the two buttons beside the musical note symbol (AN = ON, AUS = OFF).
  153. The default-setting is configurable.
  154.  
  155.  
  156.  3. Alarm
  157.  --------
  158.  
  159. To set the alarm ...
  160.  
  161.   - Click the menu-entry 'Die Uhr', the dialog will be displayed.
  162.  
  163.   - Use the buttons beside the bell symbol to switch on the alarm (AN = ON).
  164.  
  165.   - Enter the desired alarm time in the field below the bell symbol according
  166.     to the selected mode (12/24 hour display):
  167.  
  168.     24-hour mode
  169.     ============
  170.        ALWAYS enter 4 digits. Examples :
  171.  
  172.            Alarm time                   enter this
  173.          --------------------------------------------
  174.          12 past 1 am                     01:12
  175.           3 past 9 am                     09:03
  176.           5 past 2 pm                     14:05
  177.          10 past midnight                 00:10
  178.  
  179.     12-hour mode
  180.     ============
  181.        In this mode two extra buttons  AM  and  PM  are displayed.
  182.        ALWAYS enter 4 digits, and select either AM or PM.
  183.        Examples :
  184.  
  185.            Alarm time                  enter this  and  select
  186.          -------------------------------------------------------
  187.          12 past 1 am                     01:12           AM
  188.           3 past 9 am                     09:03           AM
  189.           5 past 2 pm                     02:05           PM
  190.          10 past midnight                 12:10           PM
  191.  
  192.  
  193.     Now click the button  OK, the dialog disappeares.
  194.  
  195.     If 'Die Uhr' detects an error in the alarm-time, it will display
  196.     an alert box and then re-open the dialog.
  197.  
  198.  
  199. If alarm AND time-display are switched on, a Bell symbol will be displayed
  200. as well.
  201.  
  202. To switch off the alarm before it goes off:
  203.   - open the acc. dialog (menu entry 'Die Uhr')
  204.   - select the button 'AUS' beside the bell-symbol.
  205.  
  206. As mentioned above, you cannot always be sure that 'Die Uhr' gets a chance
  207. to sound the alarm right on time. If it misses the exact time, the alarm
  208. can go off up to half an hour after the exact alarm time. If 'Die Uhr' is
  209. blocked for more then half an hour (starting with the alarm time) - I'm sorry,
  210. you missed it !
  211.  
  212.  
  213.  4. where to get the time from
  214.  -----------------------------
  215.  
  216. There are several possibilities to determine the time-of-day. Each of them
  217. has advantages and disadvantages (for configuration see 5.) :
  218.  
  219.   TIMER
  220.         When the accessory is started, the GEMDOS-time is used ONCE for
  221.         initialisation. After that the time passed since then is calculated
  222.         using the 200 Hz system timer.
  223.  
  224.         Works pretty well, just one snag: if you change the system-time
  225.         (e.g. using the control acc.) 'Die Uhr' won't notice on it's own.
  226.         So just help it by opening the accessory-dialog once to update
  227.         the time.
  228.  
  229.         ( Rumor sais there are programs that set this timer, but I doubt
  230.           that. If you set that timer the system crashes, and why should
  231.           anyone want to set it ? )
  232.  
  233.   XBIOS
  234.         fine, only ...
  235.         there is a problem if your computer doesn't have a build-in hardware
  236.         clock (e.g. the old 260 ST, 520 ST[+], 1040 STF[M], ...) .
  237.         In this case the XBIOS asks the 'intelligent' keyboard what time it
  238.         is. This confuses the screen saver of ATARI's MACCEL3 program.
  239.         MACCEL3 will -NOT- crash, but the screen saver won't work.
  240.  
  241.         Recommended for the ATARIs WITH build-in hardware clock
  242.         (MEGA ST[E], ...).
  243.  
  244.   GEMDOS
  245.         PROBLEM :
  246.         The event-critic-handler (No disk in drive A ?) calls the AES,
  247.         which allows the accessories to continue. If one of the accessories
  248.         calls the GEMDOS while the event-critic-handler is active the system
  249.         will crash (sooner or later).
  250.  
  251.         To prevent this kind of crash the screen is locked for the AES before
  252.         the GEMDOS-call using WindowUpdate ( 1 ), and afterwards released
  253.         with WindowUpdate ( 0 ).
  254.         This prevents the crash, but it also blocks 'Die Uhr' every time
  255.         another program locks the screen with WindowUpdate ( e.g. window
  256.         redraw, dialog-boxes, ...).
  257.  
  258. None of these methods is ideal, just try out which you consider best.
  259. You can select one of them in the configuration program.
  260.  
  261.  
  262.  5. configuration
  263.  ----------------
  264.  
  265. If you don't like the default settings you can change them with UHRCONF.PRG.
  266. Since version 1.1 the running accessory can be reconfigured without reset.
  267. We wrote a seperate configuration program to keep the accessory short.
  268.  
  269. Once started, UHRCONF.PRG looks for a running DIE_UHR.ACC. If the acc.
  270. is running, UHRCONF.PRG displays the settings of the RUNNING
  271. accessory; else some internal default-settings are displayed.
  272.  
  273. Now you can change the settings. If 'Die Uhr' is active, the running
  274. accessory will be notified of the changes (just look at the time-display).
  275.  
  276. other functions:
  277.  
  278.   LOAD
  279.         All settings will be loaded from a file DIE_UHR.ACC. If the
  280.         accessory is active, it will be notified of any changes.
  281.  
  282.   SAVE
  283.         Write all settings to a file DIE_UHR.ACC (the accessory).
  284.         The saved settings are the new default.
  285.  
  286.   OK
  287.         Quit the configuration program.
  288.  
  289.  
  290. If accessory- and UHRCONF.PRG- version don't match an according message is
  291. displayed. In that case nothing should crash, but I'd advise you to get an
  292. update soon.
  293.  
  294.  
  295.  
  296. APPENDIX A: The accessory's patch area           (only for the ever curious)
  297. --------------------------
  298.  
  299. Exemple and explanation:
  300.  
  301.  &Die_Uhr_Vars:TZM2k1pS&
  302.                ||||||||
  303.                |||||||+- S : seven-segment figures
  304.                |||||||   s : normal figures
  305.                |||||||
  306.                ||||||+- P : 12-hour mode
  307.                ||||||   p : 24-hour mode
  308.                ||||||
  309.                |||||+- "1" to "9" : distance from right screen edge
  310.                |||||                 (in character-width)
  311.                |||||
  312.                ||||+-- K : display italic (slanted)
  313.                ||||    k : normal display
  314.                ||||
  315.                |||+--- "1" to "9" : Update-time in seconds
  316.                |||
  317.                |||
  318.                ||+---- M : melody every full hour  ON
  319.                ||      m : --------  "  ---------  OFF
  320.                ||
  321.                |+----- Z : display ON
  322.                |       z : -- " -- OFF
  323.                |
  324.                |       Get time from ...
  325.                +------ T : 200 Hz - Timer
  326.                        X : XBIOS
  327.                        G : GEMDOS             [ see 4. ]
  328.  
  329.  
  330.  
  331.  Dokumentation by Hinnerk Rümenapf.
  332.  
  333. >> broken english spoken perfectly
  334. >> to err is human, to forgive divine
  335.  
  336. +++
  337.